<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
  Class: Sorting::Ascending
  
    &mdash; Documentation by YARD 0.8.4.1
  
</title>

  <link rel="stylesheet" href="../css/style.css" type="text/css" media="screen" charset="utf-8" />

  <link rel="stylesheet" href="../css/common.css" type="text/css" media="screen" charset="utf-8" />

<script type="text/javascript" charset="utf-8">
  hasFrames = window.top.frames.main ? true : false;
  relpath = '../';
  framesUrl = "../frames.html#!" + escape(window.location.href);
</script>


  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>

  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>


  </head>
  <body>
    <div id="header">
      <div id="menu">
  
    <a href="../_index.html">Index (A)</a> &raquo;
    <span class='title'><span class='object_link'><a href="../Sorting.html" title="Sorting (module)">Sorting</a></span></span>
     &raquo; 
    <span class="title">Ascending</span>
  

  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>

      <div id="search">
  
    <a class="full_list_link" id="class_list_link"
        href="../class_list.html">
      Class List
    </a>
  
    <a class="full_list_link" id="method_list_link"
        href="../method_list.html">
      Method List
    </a>
  
    <a class="full_list_link" id="file_list_link"
        href="../file_list.html">
      File List
    </a>
  
</div>
      <div class="clear"></div>
    </div>

    <iframe id="search_frame"></iframe>

    <div id="content"><h1>Class: Sorting::Ascending
  
  
  
</h1>

<dl class="box">
  
    <dt class="r1">Inherits:</dt>
    <dd class="r1">
      <span class="inheritName">Object</span>
      
        <ul class="fullTree">
          <li>Object</li>
          
            <li class="next">Sorting::Ascending</li>
          
        </ul>
        <a href="#" class="inheritanceTree">show all</a>
      
      </dd>
    
  
  
    
  
    
      <dt class="r2">Includes:</dt>
      <dd class="r2">Comparable</dd>
      
    
  
  
  
    <dt class="r1 last">Defined in:</dt>
    <dd class="r1 last">lib/sorting/ascending.rb</dd>
  
</dl>
<div class="clear"></div>

<h2>Overview</h2><div class="docstring">
  <div class="discussion">
    
  <div class="note notetag">
    <strong>Note:</strong>
    <div class='inline'><p>require &#39;sorting&#39; loads this class</p>
</div>
  </div>

<p>This class is used to implement &#39;asc&#39; (ascending) sorting.
You should not need to use this class directly.
You can <code>require &#39;sorting/convenience&#39;</code> and then use Kernel#asc,
or you can <code>require &#39;sorting&#39;</code> and then use Sorting#asc (which
is a module_function, and hence available as Sorting::asc)</p>


  </div>
</div>
<div class="tags">
  

  <p class="tag_title">See Also:</p>
  <ul class="see">
    
      <li><span class='object_link'><a href="Helpers.html" title="Sorting::Helpers (module)">Sorting::Helpers is a module which provides you with a convenient .asc forwarding method</a></span></li>
    
      <li><span class='object_link'><a href="../Sorting.html#asc-class_method" title="Sorting.asc (method)">Sorting.asc is the common way to create a Sorting::Ascending instance, or if you required 'sorting/convenience', then plain asc via Kernel#asc</a></span></li>
    
      <li><span class='object_link'><a href="Descending.html" title="Sorting::Descending (class)">Sorting::Descending is the opposite of Sorting::Ascending</a></span></li>
    
  </ul>

</div><div id="subclasses">
  <h2>Direct Known Subclasses</h2>
  <p class="children"><span class='object_link'><a href="Descending.html" title="Sorting::Descending (class)">Descending</a></span></p>
</div>

  <h2>Constant Summary</h2>
  
    <dl class="constants">
      
        <dt id="NilsValues-constant" class="">NilsValues =
          <div class="docstring">
  <div class="discussion">
    <p>Valid values for the treat_nils parameter of Sorting::Ascending#initialize</p>


  </div>
</div>
<div class="tags">
  

</div>
        </dt>
        <dd><pre class="code"><span class='lbracket'>[</span><span class='symbol'>:nils_first</span><span class='comma'>,</span> <span class='symbol'>:nils_last</span><span class='comma'>,</span> <span class='kw'>nil</span><span class='rbracket'>]</span></pre></dd>
      
    </dl>
  




  <h2>Instance Attribute Summary <small>(<a href="#" class="summary_toggle">collapse</a>)</small></h2>
  <ul class="summary">
    
      <li class="public ">
  <span class="summary_signature">
    
      <a href="#treat_nils-instance_method" title="#treat_nils (instance method)">- (Object) <strong>treat_nils</strong> </a>
    

    
  </span>
  
  
  
    
      <span class="note title readonly">readonly</span>
    
    
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'><p>How nils values are treated.</p>
</div></span>
  
</li>

    
  </ul>




  
    <h2>
      Instance Method Summary
      <small>(<a href="#" class="summary_toggle">collapse</a>)</small>
    </h2>

    <ul class="summary">
      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#%3C%3D%3E-instance_method" title="#&lt;=&gt; (instance method)">- (-1, ...) <strong>&lt;=&gt;</strong>(other) </a>
    

    
  </span>
  
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'><p>Comparison.</p>
</div></span>
  
</li>

      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#initialize-instance_method" title="#initialize (instance method)">- (Ascending) <strong>initialize</strong>(*args, &amp;lazy) </a>
    

    
  </span>
  
  
    <span class="note title constructor">constructor</span>
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'><p>A new instance of Ascending.</p>
</div></span>
  
</li>

      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#nils_first%3F-instance_method" title="#nils_first? (instance method)">- (Boolean) <strong>nils_first?</strong> </a>
    

    
  </span>
  
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'><p>Whether nils are always considered smaller.</p>
</div></span>
  
</li>

      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#nils_last%3F-instance_method" title="#nils_last? (instance method)">- (Boolean) <strong>nils_last?</strong> </a>
    

    
  </span>
  
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'><p>Whether nils are always considered bigger.</p>
</div></span>
  
</li>

      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#value-instance_method" title="#value (instance method)">- (Comparable, ...) <strong>value</strong> </a>
    

    
  </span>
  
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'><p>The comparable value.</p>
</div></span>
  
</li>

      
    </ul>
  


  <div id="constructor_details" class="method_details_list">
  <h2>Constructor Details</h2>
  
    <div class="method_details first">
  <h3 class="signature first" id="initialize-instance_method">
  
    
      <span class="overload">- (<tt><span class='object_link'><a href="" title="Sorting::Ascending (class)">Ascending</a></span></tt>) <strong>initialize</strong>(value, treat_nils = nil) </span>
    
      <span class="overload">- (<tt><span class='object_link'><a href="" title="Sorting::Ascending (class)">Ascending</a></span></tt>) <strong>initialize</strong>(treat_nils = nil, &amp;value) </span>
    
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    <p>A new instance of Ascending</p>


  </div>
</div>
<div class="tags">
  
  <p class="tag_title">Overloads:</p>
  <ul class="overload">
    
      
      <li class="overload_item">
        <span class="signature">- (<tt><span class='object_link'><a href="" title="Sorting::Ascending (class)">Ascending</a></span></tt>) <strong>initialize</strong>(value, treat_nils = nil) </span>
        <div class="docstring">
  <div class="discussion">
    <p>Create an ascending sorted value</p>


  </div>
</div>
<div class="tags">
  <p class="tag_title">Parameters:</p>
<ul class="param">
  
    <li>
      
        <span class='name'>value</span>
      
      
        <span class='type'>(<tt>Comparable</tt>, <tt>#&lt;=&gt;</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'><p>The value to compare.
Any object which implements &lt;=&gt; (or nil if you set treat_nils).</p>
</div>
      
    </li>
  
    <li>
      
        <span class='name'>treat_nils</span>
      
      
        <span class='type'>(<tt>nil</tt>, <tt>Symbol</tt>)</span>
      
      
        <em class="default">(defaults to: <tt>nil</tt>)</em>
      
      
        &mdash;
        <div class='inline'><p>One of nil, :nils_first, :nils_last. With nil, a normal exception
will be raised when compared with nil. With :nils_first, a nil will
always be considered smaller and hence be sorted to the beginning,
with :nils_last, a nil will always be considered bigger and hence be
sorted to the end.</p>
</div>
      
    </li>
  
</ul>


</div>
      </li>
    
      
      <li class="overload_item">
        <span class="signature">- (<tt><span class='object_link'><a href="" title="Sorting::Ascending (class)">Ascending</a></span></tt>) <strong>initialize</strong>(treat_nils = nil, &amp;value) </span>
        <div class="docstring">
  <div class="discussion">
    <p>Create an ascending sorted value, where the value is lazily computed.
This is useful for values which are expensive to compute.</p>


  </div>
</div>
<div class="tags">
  <p class="tag_title">Parameters:</p>
<ul class="param">
  
    <li>
      
        <span class='name'>treat_nils</span>
      
      
        <span class='type'>(<tt>nil</tt>, <tt>Symbol</tt>)</span>
      
      
        <em class="default">(defaults to: <tt>nil</tt>)</em>
      
      
        &mdash;
        <div class='inline'><p>One of nil, :nils_first, :nils_last. With nil, a normal exception
will be raised when compared with nil. With :nils_first, a nil will
always be considered smaller and hence be sorted to the beginning,
with :nils_last, a nil will always be considered bigger and hence be
sorted to the end.</p>
</div>
      
    </li>
  
</ul>

<p class="tag_title">Yield Returns:</p>
<ul class="yieldreturn">
  
    <li>
      
      
        <span class='type'>(<tt>Comparable</tt>, <tt>#&lt;=&gt;</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'><p>The value to compare.
Any object which implements &lt;=&gt; (or nil if you set treat_nils).</p>
</div>
      
    </li>
  
</ul>

</div>
      </li>
    
  </ul>


</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


71
72
73
74
75
76
77
78
79
80
81
82
83
84</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/sorting/ascending.rb', line 71</span>

<span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_lazy'>lazy</span><span class='rparen'>)</span>
  <span class='ivar'>@memoized</span>   <span class='op'>=</span> <span class='id identifier rubyid_lazy'>lazy</span> <span class='op'>?</span> <span class='kw'>false</span> <span class='op'>:</span> <span class='kw'>true</span>
  <span class='ivar'>@value</span>      <span class='op'>=</span> <span class='id identifier rubyid_lazy'>lazy</span> <span class='op'>||</span> <span class='id identifier rubyid_args'>args</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span>
  <span class='ivar'>@treat_nils</span> <span class='op'>=</span> <span class='id identifier rubyid_args'>args</span><span class='lbracket'>[</span><span class='id identifier rubyid_lazy'>lazy</span> <span class='op'>?</span> <span class='int'>0</span> <span class='op'>:</span> <span class='int'>1</span><span class='rbracket'>]</span>

  <span class='kw'>unless</span> <span class='const'>NilsValues</span><span class='period'>.</span><span class='id identifier rubyid_include?'>include?</span><span class='lparen'>(</span><span class='ivar'>@treat_nils</span><span class='rparen'>)</span>
    <span class='id identifier rubyid_raise'>raise</span> <span class='const'>ArgumentError</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Invalid value for nils, expected :nils_first or :nils_last, got </span><span class='embexpr_beg'>#{</span><span class='ivar'>@treat_nils</span><span class='period'>.</span><span class='id identifier rubyid_inspect'>inspect</span><span class='rbrace'>}</span><span class='tstring_end'>&quot;</span></span>
  <span class='kw'>end</span>
  <span class='kw'>if</span> <span class='id identifier rubyid_lazy'>lazy</span>
    <span class='id identifier rubyid_raise'>raise</span> <span class='const'>ArgumentError</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>wrong number of arguments (</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_args'>args</span><span class='period'>.</span><span class='id identifier rubyid_size'>size</span><span class='rbrace'>}</span><span class='tstring_content'> for 0..1</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>unless</span> <span class='id identifier rubyid_args'>args</span><span class='period'>.</span><span class='id identifier rubyid_size'>size</span><span class='period'>.</span><span class='id identifier rubyid_between?'>between?</span><span class='lparen'>(</span><span class='int'>0</span><span class='comma'>,</span> <span class='int'>1</span><span class='rparen'>)</span>
  <span class='kw'>else</span>
    <span class='id identifier rubyid_raise'>raise</span> <span class='const'>ArgumentError</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>wrong number of arguments (</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_args'>args</span><span class='period'>.</span><span class='id identifier rubyid_size'>size</span><span class='rbrace'>}</span><span class='tstring_content'> for 1..2</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>unless</span> <span class='id identifier rubyid_args'>args</span><span class='period'>.</span><span class='id identifier rubyid_size'>size</span><span class='period'>.</span><span class='id identifier rubyid_between?'>between?</span><span class='lparen'>(</span><span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='rparen'>)</span>
  <span class='kw'>end</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
  
</div>

  <div id="instance_attr_details" class="attr_details">
    <h2>Instance Attribute Details</h2>
    
      
      <span id=""></span>
      <div class="method_details first">
  <h3 class="signature first" id="treat_nils-instance_method">
  
    - (<tt>Object</tt>) <strong>treat_nils</strong>  <span class="extras">(readonly)</span>
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    <p>How nils values are treated</p>


  </div>
</div>
<div class="tags">
  

  <p class="tag_title">See Also:</p>
  <ul class="see">
    
      <li><span class='object_link'><a href="#NilsValues-constant" title="Sorting::Ascending::NilsValues (constant)">The list with all possible values</a></span></li>
    
  </ul>

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


37
38
39</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/sorting/ascending.rb', line 37</span>

<span class='kw'>def</span> <span class='id identifier rubyid_treat_nils'>treat_nils</span>
  <span class='ivar'>@treat_nils</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
  </div>


  <div id="instance_method_details" class="method_details_list">
    <h2>Instance Method Details</h2>

    
      <div class="method_details first">
  <h3 class="signature first" id="<=>-instance_method">
  
    - (<tt>-1</tt>, ...) <strong>&lt;=&gt;</strong>(other) 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    <p>Comparison. Returns -1, 0, or +1 depending on whether <code>other</code> is less
than, equal to, or greater than <code>self</code>.
Comparison with nil is special cased when #treat_nils is set.
If #treat_nils is :nils_first, it will always return 1, if it is
:nils_last, it will always return -1.
Returns nil when the value could not be compared to with <code>other</code>.</p>


  </div>
</div>
<div class="tags">
  
<p class="tag_title">Returns:</p>
<ul class="return">
  
    <li>
      
      
        <span class='type'>(<tt>-1</tt>, <tt>0</tt>, <tt>1</tt>, <tt>nil</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'><p>Comparison. Returns -1, 0, or +1 depending on whether <code>other</code> is less
than, equal to, or greater than <code>self</code>.
Comparison with nil is special cased when #treat_nils is set.
If #treat_nils is :nils_first, it will always return 1, if it is
:nils_last, it will always return -1.
Returns nil when the value could not be compared to with <code>other</code>.</p>
</div>
      
    </li>
  
</ul>

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


118
119
120
121
122
123
124
125
126
127
128
129
130
131
132</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/sorting/ascending.rb', line 118</span>

<span class='kw'>def</span> <span class='op'>&lt;=&gt;</span><span class='lparen'>(</span><span class='id identifier rubyid_other'>other</span><span class='rparen'>)</span>
  <span class='id identifier rubyid_my_value'>my_value</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span>

  <span class='kw'>if</span> <span class='ivar'>@treat_nils</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_my_value'>my_value</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
    <span class='ivar'>@treat_nils</span> <span class='op'>==</span> <span class='symbol'>:nils_first</span> <span class='op'>?</span> <span class='op'>-</span><span class='int'>1</span> <span class='op'>:</span> <span class='int'>1</span>
  <span class='kw'>else</span>
    <span class='id identifier rubyid_other_value'>other_value</span> <span class='op'>=</span> <span class='id identifier rubyid_other'>other</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span>

    <span class='kw'>if</span> <span class='ivar'>@treat_nils</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_other_value'>other_value</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
      <span class='ivar'>@treat_nils</span> <span class='op'>==</span> <span class='symbol'>:nils_first</span> <span class='op'>?</span> <span class='int'>1</span> <span class='op'>:</span> <span class='op'>-</span><span class='int'>1</span>
    <span class='kw'>else</span>
      <span class='id identifier rubyid_my_value'>my_value</span> <span class='op'>&lt;=&gt;</span> <span class='id identifier rubyid_other_value'>other_value</span>
    <span class='kw'>end</span>
  <span class='kw'>end</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
      <div class="method_details ">
  <h3 class="signature " id="nils_first?-instance_method">
  
    - (<tt>Boolean</tt>) <strong>nils_first?</strong> 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    <p>Whether nils are always considered smaller.</p>


  </div>
</div>
<div class="tags">
  
<p class="tag_title">Returns:</p>
<ul class="return">
  
    <li>
      
      
        <span class='type'>(<tt>Boolean</tt>)</span>
      
      
      
    </li>
  
</ul>

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


87
88
89</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/sorting/ascending.rb', line 87</span>

<span class='kw'>def</span> <span class='id identifier rubyid_nils_first?'>nils_first?</span>
  <span class='ivar'>@treat_nils</span> <span class='op'>==</span> <span class='symbol'>:nils_first</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
      <div class="method_details ">
  <h3 class="signature " id="nils_last?-instance_method">
  
    - (<tt>Boolean</tt>) <strong>nils_last?</strong> 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    <p>Whether nils are always considered bigger.</p>


  </div>
</div>
<div class="tags">
  
<p class="tag_title">Returns:</p>
<ul class="return">
  
    <li>
      
      
        <span class='type'>(<tt>Boolean</tt>)</span>
      
      
      
    </li>
  
</ul>

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


92
93
94</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/sorting/ascending.rb', line 92</span>

<span class='kw'>def</span> <span class='id identifier rubyid_nils_last?'>nils_last?</span>
  <span class='ivar'>@treat_nils</span> <span class='op'>==</span> <span class='symbol'>:nils_last</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
      <div class="method_details ">
  <h3 class="signature " id="value-instance_method">
  
    - (<tt>Comparable</tt>, ...) <strong>value</strong> 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    <p>The comparable value. If the Ascending object was constructed with a
lazy block, the block will be executed the first time this method is
called.</p>


  </div>
</div>
<div class="tags">
  
<p class="tag_title">Returns:</p>
<ul class="return">
  
    <li>
      
      
        <span class='type'>(<tt>Comparable</tt>, <tt>#&lt;=&gt;</tt>, <tt>nil</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'><p>The comparable value. If the Ascending object was constructed with a
lazy block, the block will be executed the first time this method is
called.</p>
</div>
      
    </li>
  
</ul>

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


101
102
103
104
105
106
107
108</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/sorting/ascending.rb', line 101</span>

<span class='kw'>def</span> <span class='id identifier rubyid_value'>value</span>
  <span class='kw'>if</span> <span class='ivar'>@memoized</span>
    <span class='ivar'>@value</span>
  <span class='kw'>else</span>
    <span class='ivar'>@memoized</span> <span class='op'>=</span> <span class='kw'>true</span>
    <span class='ivar'>@value</span>    <span class='op'>=</span> <span class='ivar'>@value</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span>
  <span class='kw'>end</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
  </div>

</div>

    <div id="footer">
  Generated on Sat Feb 23 14:24:55 2013 by
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
  0.8.4.1 (ruby-1.9.3).
</div>

  </body>
</html>